Inside Macintosh: Imaging with QuickDraw
You can use the Picture Utilities routines described in this section to gather extensive information about pictures and to gather color information about pixel maps and bitmaps. On an 8-bit indexed device, for example, you might want your application to determine the 256 most-used colors in a picture composed of millions of colors. Your application can then use the Palette Manager (as described in Inside Macintosh: Advanced Color Imaging ) to make these colors available for the window in which your application needs to draw the picture.
You use the GetPictInfo function to gather information about a single picture, and you use the GetPixMapInfo function to gather color information about a single pixel map or bitmap. Each of these functions returns color and resolution information in a PictInfo record. A PictInfo record for a picture also contains additional information, such as the resolution of the picture, and information about the fonts and comments contained in the picture.
You can also survey multiple pictures, pixel maps, and bitmaps for this information. Use the NewPictInfo function to begin collecting pictures, pixel maps, and bitmaps for your survey. You also use NewPictInfo to specify how you would like the color, comment, and font information for the survey returned to you.
To add the information for a picture to your survey, use the RecordPictInfo function. To add the information for a pixel map or a bitmap to your survey, use the RecordPixMapInfo function. The RetrievePictInfo function collects the information about the pictures, pixel maps, and bitmaps that you have added to the survey. The RetrievePictInfo function returns this information in a PictInfo record.
When you are finished with this information, use the DisposePictInfo function to dispose of the private data structures allocated by the NewPictInfo function.
The Picture Utilities also collect information from black-and-white pictures and bitmaps, and they are supported in System 7 even by computers running only basic QuickDraw. However, when collecting color information on a computer running only basic QuickDraw, the Picture Utilities return NIL instead of a handle to a Palette or ColorTable record.
Use the GetPictInfo function to gather information about a single picture.
FUNCTION GetPictInfo (thePictHandle: PicHandle;
VAR thePictInfo: PictInfo; verb: Integer;
colorsRequested: Integer;
colorPickMethod: Integer;
version: Integer): OSErr;
CONST
returnColorTable = 1; {return a ColorTable record}
returnPalette = 2; {return a Palette record}
recordComments = 4; {return comment information}
recordFontInfo = 8; {return font information}
suppressBlackAndWhite
= 16; {don't include black and }
{ white with returned colors}
CONST
systemMethod = 0; {let Picture Utilities choose }
{ the method (currently they }
{ always choose popularMethod)}
popularMethod = 1; {return most frequently used }
{ colors}
medianMethod = 2; {return a weighted distribution }
{ of colors}
In the PictInfo record to which the parameter thePictInfo points, the GetPictInfo function returns information about the picture you specify in the thePictHandle parameter. Initially, all of the fields in a new PictInfo record are set to NIL . Relevant fields are set to appropriate values depending on the information you request using the GetPictInfo function.
Use the verb parameter to specify whether you want color information (in a ColorTable record, a Palette record, or both), whether you want picture comment information, and whether you want font information. If you want color information, be sure to use the colorPickMethod parameter to specify the method by which to select colors.
The Picture Utilities provide two color-picking methods: one (specified by the popularMethod constant) that gives you the most frequently used colors and one (specified by the medianMethod constant) that gives you the widest range of colors. Each has advantages in different situations. For example, suppose the picture of a forest image contains 400 colors, of which 300 are greens, 80 are browns, and the rest are a scattering of golden sunlight effects. If you ask for the 250 most used colors, you will probably receive all greens. If you ask for a range of 250 colors, you will receive an assortment stretching from the greens and golds to the browns, including colors in between that might not actually appear in the image. If you specify the systemMethod constant, the Picture Utilities choose the method; currently they always choose popularMethod . You can also supply a color-picking method of your own.
If your application uses more than one color-picking method, it should present the user with a choice of which method to use.
When you are finished with the information in the PictInfo record, be sure to dispose of it. Use the Memory Manager procedure DisposeHandle to dispose of the PictInfo , CommentSpec , and FontSpec records. Dispose of the Palette record by using the DisposePalette procedure. Dispose of the ColorTable record by using the DisposeCTable procedure.
When you ask for color information, GetPictInfo takes into account only the version 2 and extended version 2 picture opcodes RGBFgCol , RGBBkCol , BkPixPat , PnPixPat , FillPixPat , and HiliteColor (as well as pixel map or bitmap data). Each occurrence of these opcodes is treated as 1 pixel, regardless of the number and sizes of the objects drawn with that color. If you need an accurate set of colors from a complex picture, create an image of the picture in an offscreen pixel map, and then call the GetPixMapInfo function (described on GetPixMapInfo ) to obtain color information about that pixel map.
The GetPictInfo function returns a bit depth of 1 on QuickTime-compressed 'PICT' files. However, when QuickTime is installed, QuickTime decompresses and displays the image correctly.
The PictInfo record is described on PictInfo , the CommentSpec record is described on CommentSpec , and the FontSpec record is described on FontSpec . The ColorTable record is described in the chapter "Color QuickDraw" in this book; the Palette record is described in the chapter "Palette Manager" in Inside Macintosh: Advanced Color Imaging . See "Application-Defined Routines," for more information about creating your own color-picking method for the colorPickMethod parameter.
The DisposePalette procedure is described in the chapter "Palette Manager" in Inside Macintosh: Advanced Color Imaging . The DisposeCTable procedure is described in the chapter "Color QuickDraw" in this book. The DisposeHandle procedure is described in the chapter "Memory Manager" in Inside Macintosh: Memory .
Listing 7-12 illustrates the use of the GetPictInfo function.
Use the GetPixMapInfo function to gather color information about a single pixel map or bitmap.
FUNCTION GetPixMapInfo (thePixMapHandle: PixMapHandle;
VAR thePictInfo: PictInfo; verb: Integer;
colorsRequested: Integer;
colorPickMethod: Integer;
version: Integer): OSErr;
CONST
returnColorTable = 1; {return a ColorTable record}
returnPalette = 2; {return a Palette record}
suppressBlackAndWhite
= 16; {don't include black and }
{ white with returned colors}
CONST
systemMethod = 0; {let Picture Utilities choose }
{ the method (currently they }
{ always choose popularMethod)}
popularMethod = 1; {return most frequently used }
{ colors}
medianMethod = 2; {return a weighted distribution }
{ of colors}
For the pixel map (or bitmap) whose handle you pass in the thePixMapHandle parameter, the GetPixMapInfo function returns color information in the PictInfo record that you point to in the parameter thePictInfo . Initially, all of the fields in a new PictInfo record are set to NIL . Relevant fields are set to appropriate values depending on the information you request using the GetPixMapInfo function.
Use the verb parameter to specify whether you want color information returned in a ColorTable record, a Palette record, or both, and use the colorPickMethod parameter to specify the method by which to select colors.
The Picture Utilities provide two color-picking methods: one (specified by the popularMethod constant) that gives you the most frequently used colors and one (specified by the medianMethod constant) that gives you the widest range of colors. If you specify the systemMethod constant, the Picture Utilities choose the method; currently they always choose popularMethod . You can also supply a color-picking method of your own.
When you are finished with the information in the PictInfo record, be sure to dispose of it. Use the Memory Manager procedure DisposeHandle to dispose of the PictInfo record. Dispose of the Palette record by using the DisposePalette procedure. Dispose of the ColorTable record by using the DisposeCTable procedure.
The trap macro and routine selector for the GetPixMapInfo function are
See "Application-Defined Routines," for more information about creating your own color-picking method for the colorPickMethod parameter. The PictInfo record is described on PictInfo ; the PixMapHandle data type and the ColorTable record are described in the chapter "Color QuickDraw" in this book; the Palette record is described in Inside Macintosh: Advanced Color Imaging .
The DisposePalette procedure is described in Inside Macintosh: Advanced Color Imaging . The DisposeCTable procedure is described in the chapter "Color QuickDraw" in this book. The DisposeHandle procedure is described in the chapter "Memory Manager" in Inside Macintosh: Memory .
You can survey multiple pictures for such information as colors, picture comments, and fonts, and you can survey multiple pixel maps and bitmaps for color information. Use the NewPictInfo function to begin collecting pictures, pixel maps, and bitmaps for your survey.
FUNCTION NewPictInfo (VAR thePictInfoID: PictInfoID;
verb: Integer; colorsRequested: Integer;
colorPickMethod: Integer;
version: Integer): OSErr;
CONST
returnColorTable = 1; {return a ColorTable record}
returnPalette = 2; {return a Palette record}
recordComments = 4; {return comment information}
recordFontInfo = 8; {return font information}
suppressBlackAndWhite
= 16; {don't include black and }
{ white with returned colors}
CONST
systemMethod = 0; {let Picture Utilities choose }
{ the method (currently they }
{ always choose popularMethod)}
popularMethod = 1; {return most frequently used }
{ colors}
medianMethod = 2; {return a weighted distribution }
{ of colors}
In the thePictInfoID parameter, the NewPictInfo function returns a unique ID number for use when surveying multiple pictures, pixel maps, and bitmaps for information.
To add the information for a picture to your survey, use the RecordPictInfo function, which is described next. To add the information for a pixel map or a bitmap to your survey, use the RecordPixMapInfo function, which is described on RecordPixMapInfo . For each of these functions, you identify the survey with the ID number returned by NewPictInfo .
Use the RetrievePictInfo function (described on RetrievePictInfo ) to return information about the pictures, pixel maps, and bitmaps in the survey. Again, you identify the survey with the ID number returned by NewPictInfo . The RetrievePictInfo function returns your requested information in a PictInfo record.
Use the verb parameter for NewPictInfo to specify whether you want to gather comment or font information for the pictures in the survey. If you want to gather color information, use the verb parameter for NewPictInfo to specify whether you want this information in a ColorTable record, a Palette record, or both. The PictInfo record returned by the RetrievePictInfo function will then include a handle to a ColorTable record or a Palette record, or handles to both. If you want color information, be sure to use the colorPickMethod parameter to specify the method by which to select colors.
The Picture Utilities provide two color-picking methods: one (specified by the popularMethod constant) that gives you the most frequently used colors and one (specified by the medianMethod constant) that gives you the widest range of colors. If you specify the systemMethod constant, the Picture Utilities choose the method; currently they always choose popularMethod . You can also supply a color-picking method of your own.
The PictInfo record is described on PictInfo , the CommentSpec record is described on CommentSpec , and the FontSpec record is described on FontSpec . The ColorTable record is described in the chapter "Color QuickDraw" in this book; the Palette record is described in Inside Macintosh: Advanced Color Imaging . See "Application-Defined Routines," for more information about creating your own color-picking method for the colorPickMethod parameter.
To add a picture to an informational survey of multiple pictures, use the RecordPictInfo function.
FUNCTION RecordPictInfo (thePictInfoID: PictInfoID;
thePictHandle: PicHandle): OSErr;
The RecordPictInfo function adds the picture you specify in the parameter thePictHandle to the survey of pictures identified by the parameter thePictInfoID . Use RecordPictInfo repeatedly to add additional pictures to your survey.
After you have collected all of the pictures you need, use the RetrievePictInfo function, described on RetrievePictInfo , to return information about pictures in the survey.
When you ask for color information, RecordPictInfo takes into account only the version 2 and extended version picture opcodes RGBFgCol , RGBBkCol , BkPixPat , PnPixPat , FillPixPat , and HiliteColor . Each occurrence of these opcodes is treated as 1 pixel, regardless of the number and sizes of the objects drawn with that color. If you need an accurate set of colors from a complex picture, create an image of the picture in an offscreen pixel map, and then call the GetPixMapInfo function (described on GetPixMapInfo ) to obtain color information about that pixel map.
To add a pixel map or bitmap to an informational survey of multiple pixel maps and bitmaps, use the RecordPictInfo function.
FUNCTION RecordPixMapInfo (thePictInfoID: PictInfoID;
thePixMapHandle: PixMapHandle): OSErr;
The RecordPixMapInfo function adds the pixel map or bitmap you specify in the parameter thePixMapHandle to the survey identified by the parameter thePictInfoID . Use RecordPictInfo repeatedly to add additional pixel maps and bitmaps to your survey.
After you have collected all of the images you need, use the RetrievePictInfo function, described on RetrievePictInfo , to return information about all the images in the survey.
Use the RetrievePictInfo function to return information about all the pictures, pixel maps, and bitmaps included in a survey.
FUNCTION RetrievePictInfo (thePictInfoID: PictInfoID;
VAR thePictInfo: PictInfo;
colorsRequested: Integer): OSErr;
In a PictInfo record that you point to in the parameter thePictInfo , the RetrievePictInfo function returns information about all of the pictures and images collected in the survey that you specify in the parameter thePictInfoID .
After using the NewPictInfo function to create a new survey, and then using RecordPictInfo to add pictures to your survey and RecordPixMapInfo to add pixel maps and bitmaps to your survey, you can call RetrievePictInfo .
When you are finished with the information in the PictInfo record, be sure to dispose of it. You can dispose of the Palette record by using the DisposePalette procedure. You can dispose of the ColorTable record by using the DisposeCTable procedure. You can dispose of other allocations with the DisposeHandle procedure. You should also use the DisposePictInfo function (described next) to dispose of the private data structures created by the NewPictInfo function.
The trap macro and routine selector for the RetrievePictInfo function are
When you are finished gathering information from a survey of pictures, pixel maps, or bitmaps, use the DisposePictInfo function to dispose of the private data structures allocated by the NewPictInfo function. The DisposePictInfo function is also available as the DisposPictInfo function.
FUNCTION DisposePictInfo (thePictInfoID: PictInfoID): OSErr;
The DisposePictInfo function disposes of the private data structures allocated by the NewPictInfo function, which is described on NewPictInfo .
The DisposePictInfo function does not dispose of any of the handles returned to you in a PictInfo record by the RetrievePictInfo function, which is described on RetrievePictInfo . Instead, you can dispose of a Palette record by using the DisposePalette procedure. You can dispose of a ColorTable record by using the DisposeCTable procedure. You can dispose of other allocations with the DisposeHandle procedure.